<html>
<!-- $LastChangedDate: 2011-03-16 11:12:21 -0400 (Wed, 16 Mar 2011) $ -->
<!-- Copyright (C) 2004,2009 Jim Brooks http://www.palomino3d.org -->
<head>
<title>Palomino - Lua module</title>
<link rel='stylesheet' type='text/css' href='docs.css'>
<link rel='icon' type='image/png' href='images/favicon.png'/>
</head>
<body>

<!-- ----------------------------------------------------------------------- -->
<h1>Palomino - Lua module</h1>
<p>
&copy;2004,2009&nbsp;&nbsp;Jim E. Brooks
&nbsp;&nbsp;<a href='http://www.palomino3d.org'>http://www.palomino3d.org</a>
</p>
<hr>
<ul>
  <li><a href='index.html'>Index</a></li>
  <li><a href='#Overview'>Overview</a></li>
  <li><a href='#Lua/C++ Binding Reference'>Lua/C++ Binding Reference</a></li>
  <li><a href='#Details of Bindings'>Details of Bindings</a></li>
  <li><a href='#Lua Execution'>Lua Execution</a></li>
  <li><a href='#Lua Class'>Lua Class</a></li>
  <li><a href='#C++ Classes as Lua Objects'>C++ Classes as Lua Objects</a></li>
  <li><a href='lua_scripts.html'>Lua Scripts</a></li>
</ul>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Overview'></a>
<h2>Overview</h2>
<p><!--date-->[2008/10]</p>
<p>
See also <a href='lua.html'>Lua Scripts</a>.
</p>
<p>
The <a href='http://www.lua.org'>Lua</a> interpreter
is integrated with the simulator's source code.
The simulator has a set of C functions to interface with Lua scripts.
</p>
<p>
The lua module consists of:
</p>
<pre>
src/lua_lang/  # the Lua interpreter
src/lua_bind/  # the simulator's C interface for Lua scripts
scripts/       # Lua scripts (*.lua files)
</pre>
<h3>Design Rule: C++ shouldn't depend on scripting</h3>
<p>
A design rule is that the C++ simulator core should be written
to be neutral of any scripting language.
</p>
<p>
In practice, the C++ core is integrated with a Lua interpreter.
Although, in general, the C++ core doesn't call Lua functions,
C++ has to call Lua functions to startup Lua
and broadcast timer-ticks and the
<a href='rules.html#DestroyObject Event'>DestroyObject Event</a>.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Lua/C++ Binding Reference'></a>
<h2>Lua/C++ Binding Reference</h2>
<p><!--date-->[2008/05]</p>
<p>
See the <a href='../../doxygen/namespacelua__bind.html'>lua_bind namespace</a> in doxygen.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Details of Bindings'></a>
<h2>Details of Bindings</h2>
<p><!--date-->[2011/03]</p>
<p>
In Lua, userdata requires a metatable to function as a table.
REGISTER_BINDING() essentially pre-allocates a metatable
in case a binding creates userdata represent a C++ object later using New().
So that is why the metatable isn't assigned by REGISTER_BINDING() to the class table.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Lua Execution'></a>
<h2>Lua Execution</h2>
<p><!--date-->[2008/05]</p>
<p>
The Lua interpreter stores its state in a <code>lua_State</code> struct.
This means that every time the simulator's C++ code calls Lua and Lua returns back, 
Lua remembers all of its objects, global vars, etc.
</p>
<p>
The C++ simulator calls Lua at certain points:
</p>
<ul>
<li>Lua::Startup()<img src='images/arrowGreen.gif' hspace='16'>scripts/startup.lua</li>
<li>Lua::Tick()<img src='images/arrowGreen.gif' hspace='16'>scripts/tick.lua</li>
</ul>
<p>
In turn, Lua can call a set of C functions exported to Lua by the C++ simulator.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Lua Class'></a>
<h2>Lua Class</h2>
<p><!--date-->[2008/05]</p>
<p>
This C++ class abstracts the Lua interpreter.
Lua::RunScript() has the ability to cache bytecode
in case the same Lua script is re-executed
<a href='http://lua-users.org/lists/lua-l/2003-07/msg00082.html'>[reference]</a>.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='C++ Classes as Lua Objects'></a>
<h2>C++ Classes as Lua Objects</h2>
<p><!--date-->[2011/03]</p>
<p>
To avoid C++ new/delete problems, instances of C++ classes
are created as reference-counted pointers.
C++ classes are exported to Lua as metatables.
The __gc() method is called by Lua's garbage-collector.
__gc() is implemented by DESTROY_USERDATA_SHPTR() to decrement the reference-count.
C++ delete is not called explicitly thus avoiding problems
if the simulator is still using a C++ object.
This is implemented by allocating a Lua "userdata" object.
Then C++ "placement new" is used to construct an shptr smart-pointer
at that memory location.
</p>

<!-- ********************************* END ********************************* -->
<hr>
<p align='center'>
<font size='-2'>
<!-- hhmts start -->
Last modified: Wed Mar 16 10:06:09 CDT 2011
<!-- hhmts end -->
</font>
</p>

</body>
</html>
